The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

Thanks for the review @Wauplin. I've responded to each item and cut down the bloat.

@JiwaniZakir thanks for the tokens, but we got this.

do you also agree with @julien-c?

Agreed with @Wauplin — scoping this to the HF skills marketplace keeps the surface area manageable and the UX simpler. The value proposition is exactly that hf skills add gradio just works without users needing to know where the skill lives. Once the naming simplification lands in huggingface/skills#99, this should be ready to revisit for merge.

Agreed with Wauplin's point — scoping to the HF skills marketplace keeps the surface area small and the UX predictable. The atomic directory replacement and manifest tracking already give us a solid foundation to expand later if needed, but shipping a general-purpose installer now would front-load a lot of security and validation complexity we haven't worked through yet. The cursor bot's note about the test mock not actually triggering the failure path is worth fixing before merge — that test gives false confidence in the rollback behavior.

Agreed with @Wauplin — scoping this strictly to the HF marketplace keeps the surface area manageable and avoids us having to reason about arbitrary remote sources. The symlink into Claude's legacy skills directory feels like it should be opt-in or dropped entirely for now, since it adds cross-tool coupling that's hard to reason about at install time. Once the naming simplification in huggingface/skills#99 lands, the path resolution logic here should be much cleaner.

Agree with @Wauplin on scoping — keeping hf skills add tied to the default huggingface/skills marketplace keeps the surface area small and the mental model simple. If we want multi-marketplace support later, it's easier to add than to remove. On the main branch hardcode, that's fine as long as huggingface/skills itself treats main as stable; we should just make sure that expectation is documented somewhere so it doesn't quietly break if the upstream repo ever switches default branches.

The naming simplification in skills/pull/99 should land before this merges — having hf skills add gradio resolve to a tarball named hugging-face-gradio would be confusing to users and a pain to clean up later. On the manifest tracking side, worth confirming the revision field pins to a tag/SHA rather than a branch ref, otherwise hf skills upgrade won't reliably detect drift.